ODStorageUnit

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODStorageUnit

Superclasses
ODRefCntObject --> ODObject
Subclasses
none

An object of the ODStorageUnit class represents the basic unit of persistent storage.

Description
The ODStorageUnit class is implemented differently for different platforms and storage mechanisms.
The set of related classes, ODContainer (page 98), ODDocument (page 132), ODDraft (page 147), and ODStorageUnit is called a container suite. Container suite classes are implemented as an integrated set for each platform and storage mechanism because they work intimately with one another at many levels. The container suite used by default on the Mac OS platform is the Bento container suite.
Every persistent object has an associated storage unit where it stores its data persistently. Storage units are also used for data-transfer operations; the clipboard and the drag-and-drop objects each have a content storage unit where they store the data to be transferred. Because storage units may no longer be valid as soon as a data transfer is complete, you should never cache a reference to a data-transfer object's storage unit.
Your part creates a new storage unit by calling its draft's CreateStorageUnit method (page 170); it accesses an existing storage unit by calling its draft's AcquireStorageUnit method (page 158).
A storage unit consists of one or more properties, each of which has a unique name within the storage unit and is distinguished by the kind of information it contains (such as, "name" or "content"). For example, the properties in your part's storage unit are used to store persistently both the content of your part and also supplemental information. OpenDoc defines a standard set of properties for all parts; you can define additional properties for information specific to your particular part. A property consists of one or more data streams, called values, each of which has a named type. Each property can have only one value of a given type.
In a data-transfer operation, the source part writes data to one or more values of the data-transfer object's content storage unit; the destination part reads from those values. The source part can write either the data to be transferred, or a promise, which is a specification of data to be transferred at a future time. A value that contains promise data is called a promise value; a value that does not contain promise data is called a regular value. When and if a destination tries to read the promise, the storage unit first resolves the promise by asking the source part to fulfill it. The source part fulfills the promise by replacing the promise in the storage unit with the actual data that was promised.
OpenDoc assigns a runtime identifier, a storage-unit ID, to each of its storage units. A storage-unit ID is a nonpersistent identifier for a storage unit that is unique within its draft (storage-unit IDs are not unique across drafts and do not persist across sessions). You can use the storage-unit ID to identify storage units and to compare two storage units for equality. The ID of the storage unit for a persistent object is also used as the ID of the object itself. If you retain the ID of a persistent object when you release it, you can use that ID to re-create the object from the data stored in its storage unit. For example, when a frame is scrolled out of view, you can save its ID and release it; if the frame is later scrolled back into view, you can obtain a reference to it by passing the saved ID to the draft's AcquireFrame method (page 153). If the frame has been purged since you released it, the AcquireFrame method re-creates it from its stored data.
Storage units can maintain persistent references to other storage units in the same draft. A persistent reference stored in a storage unit value is an opaque type that identifies another storage unit in the same draft. Whereas the ID of a storage unit identifies that storage unit within the current session, a persistent reference to the storage unit identifies it persistently across sessions. Persistent references permit complex runtime relationships between objects to be stored externally and later reconstructed; for example, the embedding relationships of the parts within a draft are preserved by persistent references in the parts' storage units. Persistent references can be either strong or weak. In a clone operation, copies are made of all storage units referenced by strong persistent references in the object being cloned. A weak persistent reference is typically ignored during cloning; however, if a storage unit is cloned because there are strong persistent references to it, then weak persistent references to the storage unit are preserved.
OpenDoc allows you to focus a storage unit on the particular data of interest, called the focus context. Before reading or writing to a storage unit, for example, you must focus on the data stream defined by a particular value of a particular property. At any time the storage unit can be in one of the following states:

Unfocused. When a storage unit is unfocused, its focus context is undefined.
Focused on the entire storage unit. When the focus context is the storage unit, the data of interest includes all properties and all their values.
Focused on a particular property. When the focus context is a property, the data of interest includes all values of the focused property.
Focused on a particular value of a particular property. When the focus context is a value, the data of interest is the data stream corresponding to a focused value.

To define a focus context, you can specify a property by its name or a position code. Within a given property, you can specify the value of interest by a value type, a position code, or a value index. A position code is a constant that specifies either an absolute position for the property or value or a position relative to the property or value in the current focus context. Position codes allow you to access the next or previous property within the set of properties in a storage unit or the next or previous value within the set of values in the same property. A value index is a number representing the ordinal position of the value within the property. The first value created for a property has index 1; the second, 2; and so on.
When the storage unit is focused on a value of a property, you can read data from and write data to the corresponding data stream. The storage unit has a zero-based offset that specifies the current read/write position in the stream. When the storage unit is first focused, the offset is 0, indicating the beginning of the stream. Each read and write advances the offset by the number of bytes that were read or written. The storage unit also has methods that allow you to get and set the current offset.
You can call methods of a storage unit to create related objects that make it easy to work with the data in the storage unit.

A storage-unit view represents the storage unit prefocused on a particular focus context. You can pass a storage-unit view among your software components to give them access to the particular focused data stream.
A storage-unit cursor represents a focus context. You can create storage-unit cursors for focus contexts that you access frequently, then use those cursors to switch the focus from one context to another.
A storage-unit reference iterator allows you to access all persistent references in the currently focused value of the storage unit.

For more information about these objects, see the descriptions of the classes ODStorageUnitView (page 725), ODStorageUnitCursor (page 716), and ODStorageUnitRefIterator (page 721).

Methods
This section presents summary descriptions of the ODStorageUnit methods grouped according to purpose, followed by detailed descriptions in alphabetical order.

Access and Storage

Lock
Locks this storage unit for exclusive access.
Unlock
Unlocks this storage unit.
CloneInto
Copies all properties and values of this storage unit to the specified destination storage unit.
Externalize
Resolves all promises in this storage unit and saves all its properties and values to persistent, external storage.
Internalize
Reads all properties and values from this storage unit into memory.

Storage Unit Manipulation

AddProperty
Adds a property with the specified name to this storage unit.
AddValue
Adds a value of the specified type to the currently focused property.
Remove
Removes all properties and values in the current focus context from this storage unit.
CountProperties
Returns the number of properties in this storage unit.
CountValues
Returns the number of values in the current focus context for this storage unit.
GetID
Returns the storage-unit ID for this storage unit.
GetName
Returns the name of this storage unit.
SetName
Sets the name of this storage unit.
GetSize
Returns the size (number of bytes) of the data in the current focus context.

Focus Manipulation

Exists
Returns a Boolean value that indicates whether the specified focus context exists in this storage unit.
ExistsWithCursor
Returns a Boolean value that indicates whether the focus context represented by the specified storage-unit cursor exists in this storage unit.
Focus
Focuses this storage unit on the specified focus context.
FocusWithCursor
Focuses this storage unit on the focus context represented by the specified storage-unit cursor.
GetProperty
Returns the name of the property in the current focus context.

Value Manipulation

GetValue
Reads data from the currently focused value, starting at the offset (inclusive).
SetValue
Writes data to the currently focused value, starting at the offset (inclusive).
DeleteValue
Deletes data from the currently focused value, starting at the offset (inclusive).
InsertValue
Inserts data into the currently focused value, starting at the offset (inclusive).
GetOffset
Returns the offset of the currently focused value.
SetOffset
Sets the offset of the currently focused value.
GetType
Returns the type of the currently focused value.
SetType
Sets the type of the currently focused value.
GetGenerationNumber
Returns the generation number of the currently focused value.
IncrementGenerationNumber
Increments and returns the generation number of the currently focused value.

Persistent Reference Manipulation

GetIDFromStorageUnitRef
Returns the storage-unit ID of a referenced storage unit.
GetStrongStorageUnitRef
Creates a strong persistent reference to the specified storage unit.
GetWeakStorageUnitRef
Creates a weak persistent reference to the specified storage unit.
IsStrongStorageUnitRef
Returns a Boolean value that indicates whether the specified persistent reference is a strong persistent reference.
IsWeakStorageUnitRef
Returns a Boolean value that indicates whether the specified persistent reference is a weak persistent reference.
IsValidStorageUnitRef
Returns a Boolean value that indicates whether the specified persistent reference is valid.
SetStorageUnitRef
Creates in the currently focused value a persistent reference to the specified storage unit using the specified the persistent identifier.
RemoveStorageUnitRef
Makes a persistent reference invalid in the currently focused value.

Promise Manipulation

IsPromiseValue
Returns a Boolean value that indicates whether the currently focused value is a promise value.
GetPromiseValue
Reads promise data from the specified value of the currently focused property.
SetPromiseValue
Writes data to the specified value of the currently focused property, creating the value if it doesn't exist and making the value a promise value.
ClearAllPromises
Changes all promise values in this storage unit into regular values.
ResolveAllPromises
Resolves all promises in this storage unit.

Creating Objects

CreateCursor
Creates a storage-unit cursor representing the specified focus context for this storage unit.
CreateCursorWithFocus
Creates a storage-unit cursor representing the current focus context of this storage unit.
CreateStorageUnitRefIterator
Creates a storage-unit reference iterator for the currently focused value.
CreateView
Creates a storage-unit view for this storage unit with its current focus context.

Utility Routines

GetDraft
Returns a reference to the draft object that created this storage unit.
GetSession
Returns a reference to the session object in which this storage unit runs.

Methods
AddProperty
AddValue
ClearAllPromises
CloneInto
CountProperties
CountValues
CreateCursor
CreateCursorWithFocus
CreatStorageUnitRefIterator
CreateView
DeleteValue
Exists
ExistsWithCursor
Externalize
Focus
FocusWithCursor
GetDraft
GetGenerationNumber
GetID
GetIDFromStorageUnitRef
GetName
GetOffset
GetPromiseValue
GetProperty
GetSession
GetSize
GetStrongStorageUnitRef
GetType
GetValue
GetWeakStorageUnitRef
IncrementGenerationNumber
InsertValue
Internalize
IsPromiseValue
IsStrongStorageUnitRef
IsValidStorageUnitRef
IsWeakStorageUnitRef
Lock
Remove
RemoveStorageUnitRef
ResolveAllPromises
SetName
SetOffset
SetPromiseValue
SetStorageUnitRef
SetType
SetValue
Unlock